Add a doc entry for setting up an OxCaml project with dune pkg by Sudha247 · Pull Request #12780 · ocaml/dune

Sudha247 · 2025-11-24T11:48:50Z

Adds a tutorial for setting up an OxCaml project with Dune package management.

I contemplated where this should go, and thought this might be a good place, after all. It shows (1) how to setup an OxCaml project, (2) servers as a live example of the previous two tutorials.

#12111 is a more comprehensive tutorial about parametric libraries and OxCaml, but it doesn't specifically cover the topic of Dune package management with OxCaml. I recently ported an OxCaml project to build with Dune package management and the configuration was not as straightforward as I expected, and thought a tutorial on this topic might be useful.

This takes some material from https://github.com/gridbugs/hello-oxcaml (thanks @gridbugs!).

Alizter · 2025-11-24T12:00:21Z

Here are some screenshots:

I think having these drop-down code excerpts is kind of pointless. Perhaps it would be better just to have the code inline like we do elsewhere in the docs.

Alizter · 2025-11-24T12:01:12Z

The main title doesn't need to say Example: probably.

shonfeder

Glad to have this included!

Alizter · 2025-11-26T10:08:22Z

At some point these how-to's turned into markdown rather than being rst documents which is slightly confusing. In rst we have syntax highlighting for dune files etc. Does anybody remember why markdown was chosen for these?

I would suggest writing this tutorial in rst, not only for consistency, but because it will play better with cross-linking that we have elsewhere in the docs.

Sudha247 · 2025-11-26T17:08:51Z

I would suggest writing this tutorial in rst, not only for consistency, but because it will play better with cross-linking that we have elsewhere in the docs.

I'm not opposed to doing this, but wouldn't be weird if only one of the dune-package-management entries is in rst, while others are in markdown?

Alizter · 2025-11-26T17:46:16Z

Ideally they should be all in rst, but would blow this PR out of scope. If you think it would be too much work to do in this PR, let's instead create an issue so that we remember to do it eventually. I won't block on this point.

Leonidas-from-XIV · 2025-11-26T18:25:29Z

Ah, I dug a bit around and it is because of this PR by @emillon where he notes:

it maps fully to reST

it's more contributor friendly

editor tooling is better

it alleviates some vendor lock-in (since we're likely to migrate to ocaml.org at some point, and it's more likely to use a variant of md than sphinx support odoc syntax)

Which all sound like pretty decent points.

Leonidas-from-XIV · 2025-11-27T11:31:52Z

+   (version 3.1.0+ox)))
+
+(lock_dir
+ (path "dune.lock")


This path is probably optional.

Alizter · 2025-11-27T17:02:19Z

We also have a macros for the latest dune lang version which might be sensible to use.

shonfeder · 2025-12-02T21:14:49Z

+[OxCaml](https://oxcaml.org/) project. OxCaml is a compiler branch with fast
+moving set of extensions to OCaml. Some tweaks are required to set up a project


Suggested change

[OxCaml](https://oxcaml.org/) project. OxCaml is a compiler branch with fast

moving set of extensions to OCaml. Some tweaks are required to set up a project

[OxCaml](https://oxcaml.org/) project. OxCaml is a compiler branch with a fast

moving set of extensions to OCaml. Some tweaks are required to set up a project

shonfeder · 2025-12-03T19:06:51Z

+
+(lock_dir
+ (path "dune.lock")
+ (repositories :standard oxcaml))


Suggested change

(repositories :standard oxcaml))

(pins ocamlbuild)

(repositories :standard oxcaml))

Apparently the pins in a workspace are just declarations of names (unlike pin in a dune-project, which work differently for some reason?), and to get the pin to actually pin you have also declare it for every lock_dir

Sudha247 · 2025-12-04T18:00:07Z

I've addressed all the comments. I've also made the configuration of dev tools point to the how-to guide so we have a single source of information. However, this tutorial is now hitting #12839 and #12851. But there's nothing to change in the tutorial as such.

shonfeder · 2025-12-09T18:36:52Z

Perhaps the solution for the oxcaml-side is just to undo (my suggestion of) using the lockless package management until that is fixed? We could create a TODO on the docs to simplify, and cross link from #12851, which would allow us to close this with correct information, and track the need to update it when the latter is fixed.

Does this sound like an OK way forward, @Sudha247 ?

Sudha247 · 2025-12-10T09:57:40Z

That sounds good to me. I will undo the autolocking part, write a TODO in the docs to fix this, and note it down in #12851.

Signed-off-by: Sudha Parimala <sudharg247@gmail.com>

Sudha247 · 2025-12-11T10:54:56Z

I've also added a note about dev tools. I'll cross-reference this in #12851 and go ahead and merge this if there are no objections.

@gridbugs

…#12780) Closes ocaml#11652 Adds a tutorial for setting up an OxCaml project with Dune package management. I contemplated where this should go, and thought this might be a good place, after all. It shows (1) how to setup an OxCaml project, (2) servers as a live example of the previous two tutorials. ocaml#12111 is a more comprehensive tutorial about parametric libraries and OxCaml, but it doesn't specifically cover the topic of Dune package management with OxCaml. I recently ported an OxCaml project to build with Dune package management and the configuration was not as straightforward as I expected, and thought a tutorial on this topic might be useful. This takes some material from https://github.com/gridbugs/hello-oxcaml (thanks @gridbugs!). --------- Signed-off-by: Sudha Parimala <sudharg247@gmail.com>

Sudha247 requested review from Alizter and shonfeder November 24, 2025 11:49

Alizter reviewed Nov 24, 2025

View reviewed changes